<HTML><HEAD><TITLE>library(module_options)</TITLE></HEAD><BODY>
[ <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]<H1>library(module_options)</H1>
Utility library to manage options within a library module
<H2>Predicates</H2>
<BLOCKQUOTE>
<DL>
<DT><A HREF="get_options-2.html"><STRONG>get_options(+OptionList, -OptionStruct)</STRONG></A></DT>
<DD>Create a structure OptionStruct from OptionList and the context module's default settings</DD>
<DT><A HREF="print_default_options-1.html"><STRONG>print_default_options(+Stream)</STRONG></A></DT>
<DD>Print the valid options and their current default values to Stream</DD>
<DT><A HREF="set_default_option-2.html"><STRONG>set_default_option(+OptionName, +OptionValue)</STRONG></A></DT>
<DD>Permanently set the default value for the given option in the context module</DD>
</DL>
</BLOCKQUOTE>
<H2>Description</H2>
<P>
	This library provides utilities to manage option settings on behalf
	of other library modules. The basic idea is that each client module
	can define what it considers to be valid option names and values, plus
	the structure in terms of which the set of all options will be stored
	and returned.
</P><P>
	For each client library, global default option settings are maintained
	which can be modified (in a non-backtrackable fashion) using
	set_default_option/2. Whenever the settings are retrieved, the
	defaults can be individually overridden using a user-supplied option
	list.
</P><P>
	Every client module has to define 3 local predicates:
<DL>
	<DT>valid_option_field(?Name, -FieldIndex)<DD>
	    defines the option names (atoms) and the position (integer)
	    of the option value within an option structure.
	<DT>valid_option_value(+Name, +Value)<DD>
	    defines what constitues a valid option value, by
	    provides a type/range check for Value. The predicate should
	    fail if Value is not a valid value for option Name.
	<DT>default_options(-OptionStructure)<DD>
	    this should be a single fact which should return a structure.
	    The structure arguments define the initial default settings
	    for each option field. The structure's functor defines the
	    skeleton in terms of which option settings will be returned
	    by get_options/2.
	    Note that the structure can have extra fields which are
	    not defined as valid options, are not user-modifiable, and
	    will therefore always be returned unchanged by get_options/2.
</DL>
	A typical application would in addition define a toplevel predicate
	that accepts a user-supplied option list per invocation, and possibly
	a predicate to modify the global default settings.  Sample usage:
<PRE>
	:- module(my_module).

	:- lib(module_options).

	valid_option_field(a, 1).
	valid_option_field(b, 2).
	valid_option_field(c, 3).

	valid_option_value(a, Value) :- integer(Value).
	valid_option_value(b, Value) :- atom(Value).
	valid_option_value(c, Value) :- atom(Value).

	default_options(options(23,hello,world,there)).

	:- export my_set_default_option/2.
	my_set_default_option(Name, Value) :-
	    set_default_option(Name, Value).

	:- export my_predicate/2.
	my_predicate(Arguments, OptionList) :-
	    ( get_options(OptionList, OptionStruct) ->
		...
	    ;
		printf(error, "Invalid option list: %w%n", [OptionList]),
		print_default_options(error),
		abort
	    ).
</PRE>
	In practice, it is recommended to use structure notation for the
	option structure for better readability and maintainability, i.e.
<PRE>
	:- module(my_module).

	:- lib(module_options).

	:- local struct(options(a,b,c,d)).

	valid_option_field(a, a of options).
	valid_option_field(b, b of options).
	valid_option_field(c, c of options).

	valid_option_value(a, Value) :- integer(Value).
	valid_option_value(b, Value) :- atom(Value).
	valid_option_value(c, Value) :- atom(Value).

	default_options(options{a:23,b:hello,c:world,d:there}).

	:- export my_set_default_option/2.
	my_set_default_option(Name, Value) :-
	    set_default_option(Name, Value).

	:- export my_predicate/2.
	my_predicate(Arguments, OptionList) :-
	    ( get_options(OptionList, OptionStruct) ->
		...
	    ;
		printf(error, "Invalid option list: %w%n", [OptionList]),
		print_default_options(error),
		abort
	    ).
</PRE>
	It is not absulotely necessary to define a predicate like
	my_set_default_option/2 since <CODE>my_set_default_option(opt,val)</CODE>
	is equivalent to <CODE>set_default_option(opt,val)@my_module</CODE>.
</P>

<H2>About</H2><UL COMPACT>
<LI><STRONG>Author: </STRONG>Joachim Schimpf
<LI><STRONG>Copyright &copy; </STRONG>Cisco Systems, Inc
<LI><STRONG>Date: </STRONG>$Date: 2009/03/16 08:50:28 $
</UL>
<HR>Generated from module_options.eci on 2009-05-27 01:25
</BODY></HTML>
